---
title: 이미지
description: Astro에서 이미지를 사용하는 방법을 알아보세요.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Badge from '~/components/Badge.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";

Astro는 프로젝트 내부에 로컬로 저장되거나, 외부 URL에서 연결되거나, CMS 또는 CDN에서 관리되는 등 사이트에서 이미지를 사용할 수 있는 여러 가지 방법을 제공합니다!

## 이미지 저장 위치

### `src/` vs `public/`

Astro가 이미지를 변환, 최적화, 번들링할 수 있도록 가능하면 로컬 이미지를 `src/`에 보관하는 것이 좋습니다. `/public` 디렉터리의 파일은 처리 없이 항상 있는 그대로 빌드 폴더에 제공되거나 복사됩니다.

`src/`에 저장된 로컬 이미지는 `.astro`, `.md`, `.mdx`, `.mdoc` 및 기타 UI 프레임워크 등 프로젝트의 모든 파일에서 사용할 수 있습니다. 이미지는 콘텐츠 근처를 포함하여 모든 폴더에 저장할 수 있습니다.

이미지 처리를 피하거나 이미지에 대한 직접 공개 링크를 갖고 싶다면 `public/` 폴더에 이미지를 저장하세요.

### 원격 이미지

CMS (콘텐츠 관리 시스템) 또는 DAM (디지털 자산 관리) 플랫폼에 이미지를 원격으로 저장하도록 선택할 수도 있습니다.

외부 소스를 처리할 때 추가 보호를 위해 원격 이미지는 구성에 지정된 [승인된 이미지 소스](#원격-이미지-승인)에서만 처리됩니다. 그러나 모든 원격 이미지는 표시될 수 있습니다.

Astro는 API를 사용하여 원격으로 데이터를 가져오거나 전체 URL 경로에서 이미지를 표시할 수 있습니다. 공통 서비스 통합의 예시는 [CMS 안내서](/ko/guides/cms/)를 참조하세요.

## `.astro` 파일의 이미지

`.astro` 파일에서 **사용하려면 로컬 이미지를 파일로 가져와야 합니다**. 원격 및 `public/` 이미지는 가져올 필요가 없습니다.

`astro:assets`를 사용하여 최적화된 이미지를 위해 Astro의 내장 `<Image />` 컴포넌트를 가져와 사용하세요. 또는 Astro 구문은 이미지 처리를 건너뛰는 HTML `<img>` 태그 직접 작성을 지원합니다.

```astro title="src/pages/blog/my-images.astro"
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">
```

`src/` 폴더에서 이미지를 동적으로 가져오려면 다음 레시피를 참조하세요.

<RecipeLinks slugs={["ko/recipes/dynamically-importing-images" ]}/>

### `<Image />` (`astro:assets`)

내장된 `<Image />` Astro 컴포넌트를 사용하여 로컬 이미지와 [구성된 원격 이미지](#원격-이미지-승인)의 최적화된 버전을 표시하세요.

`public/` 폴더에 있는 이미지와 프로젝트에 특별히 구성되지 않은 원격 이미지도 이미지 컴포넌트와 함께 사용할 수 있지만 처리되지는 않습니다.

`<Image />`는 표시된 이미지를 제어하기 위해 로컬 또는 인증된 원격 이미지의 크기, 파일 유형 및 품질을 변환할 수 있습니다. 결과 `<img>` 태그에는 `alt`, `loading` 및 `decoding` 속성이 포함되며 **CLS (Cumulative Layout Shift)** 를 방지하기 위해 이미지 크기를 유추합니다.

:::tip[Cumulative Layout Shift란 무엇입니까?]
[CLS (Cumulative Layout Shift)](https://web.dev/cls/)는 로드하는 동안 페이지에서 콘텐츠가 얼마나 이동했는지 측정하기 위한 Core Web Vital 지표입니다. `<Image />` 컴포넌트는 로컬 이미지에 대해 올바른 `width` 및 `height`를 자동으로 설정하여 CLS에 맞게 최적화합니다.
:::

```astro title="src/components/MyComponent.astro"
---
// 이미지 컴포넌트와 이미지 가져오기
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="A description of my image." />
```

```html
<!-- 결과물 -->
<!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>
```

#### 속성

##### src (필수)

이미지 파일의 `src` 값 형식은 이미지 파일의 위치에 따라 다릅니다.

- **`src/`의 로컬 이미지** - 상대 파일 경로를 사용하여 **이미지도 가져오거나** [가져오기 별칭](/ko/guides/aliases/)을 구성하고 사용해야 합니다. 그런 다음 가져오기 이름을 `src` 값으로 사용합니다.

  ```astro title="src/pages/index.astro" "myImportedImage" "{myImportedImage}"
  ---
  import { Image } from 'astro:assets';
  import myImportedImage from '../assets/my-local-image.png';
  ---
  <Image src={myImportedImage} alt="descriptive text" />
  ```

- **`public/` 폴더의 이미지** - 이미지의 **public 폴더에 상대적인 파일 경로** 사용:

  ```astro title="src/pages/index.astro" '"/images/my-public-image.png"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/images/my-public-image.png"
    alt="descriptive text"
    width="200"
    height="150"
  />
  ```

- **원격 이미지** - 이미지의 **전체 URL**을 속성 값으로 사용합니다.

  ```astro title="src/pages/index.astro" '"https://example.com/remote-image.jpg"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://example.com/remote-image.jpg"
    alt="descriptive text"
    width="200"
    height="150"
  />
  ```

##### alt (필수)

이미지에 대한 [설명 대체 텍스트](https://www.w3.org/WAI/tutorials/images/) 문자열을 제공하려면 필수 `alt` 속성을 사용하세요.

이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) `alt=""`를 설정하여 화면 판독기 및 기타 보조 기술이 이미지를 무시하도록 알립니다.

##### width 및 height (`public/`의 이미지에 필요)

이러한 속성은 이미지에 사용할 크기를 정의합니다.

이미지를 원본 가로세로 비율로 사용하는 경우 `width` 및 `height`는 선택사항입니다. 이러한 크기는 `src/` 디렉터리에 있는 이미지 파일과 [`inferSize`가 `true`로 설정된](#infersize) 원격 이미지에서 자동으로 추론될 수 있습니다.

그러나 Astro는 이러한 파일을 분석할 수 없으므로 `public/` 폴더에 저장된 이미지에는 이 두 속성이 모두 필요합니다.

##### densities

<p><Since v="3.3.0" /></p>

이미지에 대해 생성할 픽셀 밀도 목록입니다.

제공된 경우 이 값은 `<img>` 태그에 `srcset` 속성을 생성하는 데 사용됩니다. 이 값을 사용할 때 `widths` 값을 제공하지 마세요.

이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 더 큰 너비와 동일한 밀도는 무시됩니다.

```astro title="src/components/MyComponent.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image 
  src={myImage} 
  width={myImage.width / 2} 
  densities={[1.5, 2]} 
  alt="A description of my image."
/>
```

```html
<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="A description of my image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

##### widths

<p><Since v="3.3.0" /></p>

이미지에 대해 생성할 너비 목록입니다.

제공된 경우 이 값은 `<img>` 태그에 `srcset` 속성을 생성하는 데 사용됩니다. [`sizes` 속성](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes)도 제공해야 합니다.

이 값을 사용할 때는 `densities` 값을 제공하지 마세요. 이 두 값 중 하나만 사용하여 `srcset`을 생성할 수 있습니다.

이미지 크기가 커지는 것을 방지하기 위해 원본 이미지보다 큰 너비는 무시됩니다.

```astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---
<Image
  src={myImage}
  widths={[240, 540, 720, myImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}
  alt="A description of my image."
/>
```

```html
<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 240w,
    /_astro/my_image.hash.webp 540w,
    /_astro/my_image.hash.webp 720w,
		/_astro/my_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="A description of my image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
```

##### format

선택적으로 사용할 [이미지 파일 형식](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) 출력을 명시할 수 있습니다.

기본적으로 `<Image />` 컴포넌트는 `.webp` 파일을 생성합니다.

##### quality

`quality`는 다음 중 하나일 수 있는 선택적 속성입니다.
- 형식 간 자동으로 표준화되는 사전 설정 (`low`, `mid`, `high`, `max`)입니다.
- `0`부터 `100`까지의 숫자 (형식에 따라 다르게 해석됨)

##### inferSize

<p><Since v="4.4.0" /></p>

원격 이미지의 원래 `width` 및 `height`를 자동으로 설정할 수 있습니다.

기본적으로 이 값은 `false`로 설정되어 있어 원격 이미지에 두 크기를 모두 수동으로 지정해야 합니다.

`<Image />` 컴포넌트에 `inferSize`를 추가하거나 `getImage()`에 `inferSize: true`를 추가하여 가져올 때 이미지 콘텐츠에서 이러한 값을 추론합니다. 이는 원격 이미지의 크기를 모르거나 변경될 수 있는 경우에 유용합니다.

```astro mark="inferSize"
---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="A cat sleeping in the sun." />
```

`inferSize`는 [승인되지 않은 도메인의 원격 이미지](#원격-이미지-승인)의 크기를 가져올 수 있지만 이미지 자체는 처리되지 않은 상태로 유지됩니다.

##### 추가 속성

위 속성 외에도 `<Image />` 컴포넌트는 HTML `<img>` 태그에서 허용하는 모든 속성을 허용합니다.

예를 들어, 최종 `<img>` 요소에 `class`를 제공할 수 있습니다.

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- 이미지 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="" class="my-class" />
```

```html
<!-- 출력 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>
```

#### 기본값 설정

현재 모든 `<Image />` 컴포넌트에 대한 기본값을 지정할 수 있는 방법은 없습니다. 필수 속성은 각 개별 컴포넌트에 설정되어야 합니다.

대안으로 재사용을 위해 이러한 컴포넌트를 다른 Astro 컴포넌트로 래핑할 수 있습니다. 예를 들어 블로그 게시물 이미지에 대한 컴포넌트를 만들 수 있습니다.

```astro title="src/components/BlogPostImage.astro"
---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

### `<Picture />`

<p><Since v="3.3.0" /></p>

다양한 형식 및 크기로 반응형 이미지를 표시하려면 내장된 `<Picture />` Astro 컴포넌트를 사용하세요.

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900의 이미지
---

<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. -->
<Picture 
  src={myImage} 
  formats={['avif', 'webp']} 
  alt="A description of my image." 
/>
```

```html
<!-- 출력 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>
```

#### 속성

`<Picture />`는 `<Image />` 컴포넌트의 모든 속성과 함께 다음을 허용합니다.

##### `formats`

`<source>` 태그에 사용할 이미지 형식의 배열입니다. 항목은 나열된 순서대로 `<source>` 요소로 추가되며, 이 순서에 따라 표시되는 형식이 결정됩니다. 최상의 성능을 얻으려면 가장 최신 형식 (예: `webp` 또는 `avif`)을 먼저 나열하세요. 기본적으로 `['webp']`로 설정되어 있습니다.

##### `fallbackFormat`

`<img>` 태그에 대한 대체 값으로 사용할 형식입니다.

정적 이미지의 기본값은 `.png` (또는 이미지가 JPG인 경우 `.jpg`), 애니메이션 이미지의 경우 `.gif`, SVG 파일의 경우 `.svg`입니다.

##### `pictureAttributes`

`<picture>` 태그에 추가될 속성의 객체입니다.

이 속성을 사용하여 외부 `<picture>` 요소 자체에 특성을 적용합니다. `<Picture />` 컴포넌트에 직접 적용된 속성은 이미지 변환에 사용되는 속성을 제외하고 내부 `<img>` 요소에 적용됩니다.

```astro title="src/components/MyComponent.astro"
---
import { Picture } from "astro:assets";
import myImage from "../my_image.png"; // 1600x900의 이미지
---

<Picture src={myImage} alt="A description of my image." pictureAttributes={{style: "background-color: red;"}} />
```

```html
<picture style="background-color: red;">
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    alt="A description of my image."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>
```

### `<img>`

[Astro 템플릿 구문](/ko/basics/astro-syntax/)은 `<img>` 태그 직접 작성도 지원하며 최종 출력을 완전히 제어할 수 있습니다. 이러한 이미지는 처리 및 최적화되지 않습니다.

모든 HTML `<img>` 태그 속성을 허용하며 유일한 필수 속성은 `src`입니다.

#### `src/`의 로컬 이미지

로컬 이미지는 기존 `.astro` 파일의 **상대 경로에서 가져오거나** [가져오기 별칭](/ko/guides/aliases/)을 구성하고 사용해야 합니다. 그런 다음 이미지의 `src` 및 `<img>` 태그에 사용할 기타 속성에 액세스할 수 있습니다.

예를 들어, CLS를 방지하고 Core Web Vitals를 개선하려면 이미지 자체의 `height` 및 `width` 속성을 사용하세요.

```astro title="src/pages/posts/post-1.astro" "myDog.width" "myDog.height"
---
// 로컬 이미지 가져오기
import myDog from '../../images/pets/local-dog.jpg';
---
// 이미지 속성에 액세스
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="A barking dog." />
```

가져온 이미지 자산은 다음 시그니처와 일치합니다.

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

#### `public/`의 이미지

`public/`에 있는 이미지의 경우 `src` 값으로 이미지의 **public 폴더에 상대적인 파일 경로**를 사용합니다.

```astro '"/images/public-cat.jpg"'
<img src="/images/public-cat.jpg" alt="A sleeping cat." >
```

#### 원격 이미지

원격 이미지의 경우 이미지의 **전체 URL**을 `src` 값으로 사용하세요.

```astro '"https://example.com/remote-cat.jpg"'
<img src="https://example.com/remote-cat.jpg" alt="A sleeping cat." >
```

### `<Image />` vs `<img>` 선택

`<Image />` 컴포넌트는 이미지를 최적화하고 CLS를 방지하기 위해 원본 가로 세로 비율을 기반으로 (로컬 이미지의) 너비와 높이를 추론합니다.

`<Image />` 컴포넌트를 사용할 수 없는 경우 HTML `<img>` 요소를 사용하세요. 예를 들면 다음과 같습니다.
  - 지원되지 않는 이미지 형식의 경우
  - Astro로 이미지 최적화를 원하지 않는 경우
  - 클라이언트 측에서 `src` 속성에 동적으로 액세스하고 변경하려는 경우

### 원격 이미지 승인

[`image.domains`](/ko/reference/configuration-reference/#imagedomains) 및 [`image.remotePatterns`](/ko/reference/configuration-reference/#imageremotepatterns)을 사용하여 이미지 최적화를 위해 인증된 이미지 소스 URL 도메인 및 패턴 목록을 구성할 수 있습니다. 이 구성은 외부 소스의 이미지를 표시할 때 사이트를 보호하기 위한 추가 안전 계층입니다.

다른 소스의 원격 이미지는 최적화되지 않지만 이러한 이미지에 `<Image />` 컴포넌트를 사용하면 CLS (Cumulative Layout Shift)가 방지됩니다.

예를 들어 다음 구성에서는 `astro.build`의 원격 이미지만 최적화할 수 있습니다.

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

다음 구성은 HTTPS 호스트의 원격 이미지만 허용합니다.

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## CMS 또는 CDN의 이미지 사용

이미지 CDN은 모든 Astro 이미지 옵션에서 작동합니다. 이미지의 전체 URL을 `<Image />` 컴포넌트, `<img>` 태그 또는 Markdown 표기법에서 `src` 속성으로 사용하세요. 원격 이미지로 이미지를 최적화하려면 [승인된 도메인 또는 URL 패턴을 구성](#원격-이미지-승인)하세요.

또는 CDN이 Node.js SDK를 제공하는 경우 이를 프로젝트에서 사용할 수 있습니다. 예를 들어, [Cloudinary의 SDK](https://cloudinary.com/documentation/node_integration)는 적절한 `src`가 포함된 `<img>` 태그를 생성할 수 있습니다.

## Markdown 파일의 이미지

`.md` 파일에 표준 Markdown `![alt](src)` 구문을 사용하세요. 이 구문은 Astro의 [이미지 서비스 API](/ko/reference/image-service-reference/)와 함께 작동하여 로컬 이미지와 승인된 원격 이미지를 최적화합니다.

```md
<!-- src/pages/post-1.md -->

# My Markdown Page

<!-- src/assets/에 저장된 로컬 이미지 -->
<!-- 상대 파일 경로 또는 가져오기 별칭 사용 -->
![A starry night sky.](../assets/stars.png)

<!-- public/images/에 저장된 이미지 -->
<!-- public/에 상대적인 파일 경로를 사용 -->
![A starry night sky.](/images/stars.png)

<!-- 다른 서버의 원격 이미지 -->
<!-- 이미지의 전체 URL을 사용 -->
![Astro](https://example.com/images/remote-image.png)
```

로컬 이미지에는 `<img>` 태그가 지원되지 않으며 `.md` 파일에서는 `<Image />` 컴포넌트를 사용할 수 없습니다.

이미지 속성에 대한 더 많은 제어가 필요한 경우 Markdown 구문 외에 Astro의 `<Image />` 컴포넌트 또는 JSX `<img />` 태그를 포함할 수 있는 `.mdx` 파일 형식을 사용하는 것이 좋습니다. [MDX 통합](/ko/guides/integrations-guide/mdx/)을 사용하여 Astro에 MDX 지원을 추가하세요.

## MDX 파일의 이미지

컴포넌트와 이미지를 모두 가져와 `.mdx` 파일에서 Astro의 `<Image />` 컴포넌트와 JSX `<img />` 태그를 사용할 수 있습니다. [`.astro` 파일에서 사용되는 것](#astro-파일의-이미지)처럼 사용하십시오.

또한 가져오기가 필요 없는 [표준 Markdown `![alt](src)` 구문](#markdown-파일의-이미지)이 지원됩니다.

```mdx title="src/pages/post-1.mdx"
---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# My MDX Page

// src/assets/에 저장된 로컬 이미지
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)

// public/images/에 저장된 이미지
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)

// 다른 서버의 원격 이미지
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)
```

## 콘텐츠 컬렉션의 이미지

콘텐츠 컬렉션의 이미지는 사용 중인 파일 형식에 따라 [Markdown](#markdown-파일의-이미지) 및 [MDX](#mdx-파일의-이미지)에서와 동일한 방식으로 처리됩니다.

또한 현재 폴더에 대한 상대 경로를 사용하여 블로그 게시물의 표지 이미지와 같은 콘텐츠 컬렉션 항목 관련 이미지를 본문에 선언할 수 있습니다.

```md title="src/content/blog/my-post.md" {3}
---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # "src/content/blog/firstblogcover.jpeg"로 해석됩니다.
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post
```

콘텐츠 컬렉션 스키마의 `image` 도우미를 사용하면 Zod를 사용하여 이미지 메타데이터의 유효성을 검사할 수 있습니다.

```ts title="src/content/config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image().refine((img) => img.width >= 1080, {
			message: "Cover image must be at least 1080 pixels wide!",
		}),
		coverAlt: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

이미지를 가져와서 메타데이터로 변환하므로 이를 `<Image/>`, `<img>`, `getImage()`에 `src`로 전달할 수 있습니다.

아래 예시는 위 스키마에서 각 블로그 게시물의 표지 사진과 제목을 렌더링하는 블로그 인덱스 페이지를 보여줍니다.

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## UI 프레임워크 컴포넌트의 이미지

UI 프레임워크 컴포넌트에 이미지를 추가할 때 프레임워크의 자체 이미지 구문을 사용하여 이미지를 렌더링합니다 (예: JSX의 `<img />`, Svelte의 `<img>`).

`src`와 같은 [이미지 속성](#src의-로컬-이미지)에 액세스하려면 로컬 이미지를 **먼저 가져와야** 합니다.

```jsx title="src/components/ReactImage.jsx"
import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="A starry night sky." />
  )
}
```

```svelte title="src/components/SvelteImage.svelte"
<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="A starry night sky." />

```

#### 이미지 컴포넌트 전달

다른 Astro 컴포넌트와 마찬가지로 `<Image />` 컴포넌트는 **UI 프레임워크 컴포넌트에서 사용할 수 없습니다**.

그러나 `<Image />`에서 생성된 정적 콘텐츠를 `.astro` 파일 내 프레임워크 컴포넌트에 하위 항목으로 전달하거나 [명명된 `<slot/>`](/ko/guides/framework-components/#프레임워크-컴포넌트-중-astro-컴포넌트를-사용할-수-있나요)을 사용하여 전달할 수 있습니다.

```astro title="ImageWrapper.astro"
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="A starry night sky." />
</ReactComponent>
```

## `getImage()`를 사용하여 이미지 생성하기

:::caution
`getImage()`는 서버 전용 API에 의존하며 클라이언트에서 사용될 때 빌드를 중단합니다.
:::

`getImage()` 함수는 HTML이 아닌 다른 곳 (예: [API 경로](/ko/guides/endpoints/#서버-엔드포인트-api-라우트))에서 사용할 이미지를 생성하기 위한 것입니다. 또한 사용자 정의 `<Image />` 컴포넌트를 만들 수도 있습니다.

<RecipeLinks slugs={["ko/recipes/build-custom-img-component" ]}/>

`getImage()`는 [이미지 컴포넌트와 동일한 속성](#속성) (`alt` 제외)을 가진 옵션 객체를 사용합니다.

```astro
---
import { getImage } from "astro:assets";
import myBackground from "../background.png";

const optimizedBackground = await getImage({src: myBackground, format: 'webp'});
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>
```

다음 속성을 가진 객체를 반환합니다.

```js
{
  rawOptions: {...}, // 기존에 전달된 매개변수
  options: {...}, // 전달된 검증된 매개변수
  src: "...", // 생성된 이미지의 경로
  srcSet: {
    values: [...], // srcset에 대해 생성된 값, 모든 항목에는 URL과 크기 설명자가 있습니다.
    attribute: "", // values에서 생성된 srcset 속성
  }
  attributes: {...} // 이미지를 렌더링하는 데 필요한 추가 HTML 속성 (width, height, style 등)
}
```

## 대체 텍스트

모든 사용자가 동일한 방식으로 이미지를 볼 수 있는 것은 아니므로 이미지를 사용할 때 접근성은 특히 중요한 고려사항입니다. 이미지에 대한 [설명 대체 텍스트](https://www.w3.org/WAI/tutorials/images/)를 제공하려면 `alt` 속성을 사용하세요.

이 속성은 `<Image />` 및 `<Picture />` 컴포넌트 모두에 필요합니다. 대체 텍스트가 제공되지 않으면 `alt` 속성을 포함하라는 유용한 오류 메시지가 제공됩니다.

이미지가 단지 장식용인 경우 (즉, 페이지 이해에 도움이 되지 않는 경우) 화면 판독기가 이미지를 무시할 수 있도록 `alt=""`를 설정하세요.

## 기본 이미지 서비스

[Sharp](https://github.com/lovell/sharp)는 `astro:assets`에 사용되는 기본 이미지 서비스입니다. [`image.service`](/ko/reference/configuration-reference/#imageservice) 옵션을 사용하여 이미지 서비스를 추가로 구성할 수 있습니다.

:::note
`pnpm`과 같은 [엄격한 패키지 관리자](https://pnpm.io/pnpm-vs-npm#npms-flat-tree)를 사용하는 경우 Astro 종속성임에도 불구하고 Sharp를 프로젝트에 수동으로 설치해야 할 수 있습니다.

```bash
pnpm add sharp
```
:::

### Squoosh 구성

[Squoosh](https://github.com/GoogleChromeLabs/squoosh)를 사용하여 이미지를 변환하려면 다음과 같이 구성을 업데이트하세요.

```js title="astro.config.mjs" ins={4-6}
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

### 무작동 패스스루 서비스 구성

[`server` 또는 `hybrid` 모드용 어댑터](https://astro.build/integrations/?search=&categories%5B%5D=adapters)가 Astro의 내장 Squoosh 및 Sharp 이미지 최적화를 지원하지 않는 경우 (예: Deno, Cloudflare) `<Image />` 및 `<Picture />` 컴포넌트를 사용할 수 있도록 무작동 이미지 서비스를 구성할 수 있습니다. Astro는 이러한 환경에서 이미지 변환 및 처리를 수행하지 않습니다. 그러나 CLS (Cumulative Layout Shift) 없음, 강제된 `alt` 속성 및 일관된 작성 환경을 포함하여 `astro:assets` 사용의 다른 이점을 계속 누릴 수 있습니다.

Squoosh 및 Sharp 이미지 처리를 모두 방지하려면 `passthroughImageService()`를 구성하세요.

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## 커뮤니티 통합

Astro 프로젝트의 이미지를 최적화하고 작업하기 위한 여러 타사 [커뮤니티 이미지 통합](https://astro.build/integrations?search=images)이 있습니다.

## v2.x에서 v3.0으로 업그레이드

`astro:assets`는 더 이상 Astro v3.0의 실험적 플래그 뒤에 있지 않습니다.

`<Image />`는 이제 내장 컴포넌트이며 이전 `@astrojs/image` 통합은 제거되었습니다.

Astro에서 이미지 사용에 대한 이러한 변경 사항 및 기타 수반되는 변경 사항은 Astro 프로젝트를 이전 버전에서 업그레이드할 때 일부 주요 변경 사항을 초래할 수 있습니다.

Astro v2.x 프로젝트를 v3.0으로 업그레이드하려면 아래 지침을 적절하게 따르세요.

### `experimental.assets`에서 업그레이드

이전에 `astro:assets`에 대한 실험적 플래그를 활성화한 경우 이제 기본적으로 자산 기능이 포함된 Astro v3.0용으로 프로젝트를 업데이트해야 합니다.

#### `experimental.assets` 플래그 제거

실험적 플래그를 제거합니다.

```js title="astro.config.mjs" del={4-6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});
```

필요한 경우 `astro/client-image` 참조를 `astro/client`로 바꾸도록 `src/env.d.ts` 파일도 업데이트하세요.

```ts title="src/env.d.ts" del={1} ins={2}
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />
```

#### `~/assets` 가져오기 별칭 제거

이 가져오기 별칭은 더 이상 `astro:assets`에 기본적으로 포함되지 않습니다. 실험적 자산과 함께 이 별칭을 사용하는 경우 이를 상대 파일 경로로 변환하거나 [자신만의 가져오기 별칭을 생성](/ko/guides/aliases/)해야 합니다.

```astro title="src/pages/posts/post-1.astro" del={2} ins={3}
---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---
```

#### Cloudflare, Deno, Vercel Edge, Netlify Edge에 대한 간단한 자산 지원 추가

 Astro v3.0을 사용하면 Astro의 기본 제공 Squoosh 및 Sharp 이미지 최적화를 지원하지 않는 Cloudflare, Deno, Vercel Edge, Netlify Edge에서 `astro:assets`가 오류 없이 작동할 수 있습니다. Astro는 이러한 환경에서 이미지 변환 및 처리를 수행하지 않습니다. 그러나 CLS (Cumulative Layout Shift) 없음, 강제된 `alt` 속성 및 일관된 작성 환경을 포함하여 `astro:assets` 사용의 다른 이점을 계속 누릴 수 있습니다.

 이전에는 이러한 제약으로 인해 `astro:assets` 사용을 피했다면 이제 문제 없이 사용할 수 있습니다. 이 동작을 명시적으로 선택하도록 무작동 이미지 서비스를 구성할 수 있습니다.

```js title="astro.config.mjs" ins={4-8}
import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});
```

### 이미지를 저장할 위치 결정

[이미지를 저장할 위치](#이미지-저장-위치)를 결정하는 데 도움이 되는 이미지 안내서를 참조하세요. `astro:assets`가 제공하는 유연성을 추가하여 이미지를 저장하는 새로운 옵션을 활용하고 싶을 수도 있습니다. 예를 들어, 이제 표준 Markdown `![alt](src)` 구문을 사용하여 `src/` 프로젝트의 상대 이미지를 Markdown, MDX, Markdoc에서 참조할 수 있습니다.

### 기존 `<img>` 태그 업데이트

이전에는 이미지를 가져오면 이미지 경로가 포함된 간단한 `string`이 반환되었습니다. 이제 가져온 이미지 자산은 다음 시그니처와 일치합니다.

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

기존 `<img>` 태그 ([UI 프레임워크 컴포넌트의 이미지](#ui-프레임워크-컴포넌트의-이미지) 포함)의 `src` 속성을 업데이트해야 하며 가져온 이미지에서 현재 사용할 수 있는 다른 속성도 업데이트할 수도 있습니다.

```astro title="src/components/MyComponent.astro" ".src" ".width" ".height" del={4} ins={6}
---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="A rocketship in space." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />
```

### Markdown, MDX, Markdoc 파일 업데이트

이제 프로젝트 `src/`의 상대 이미지를 표준 Markdown `![alt](src)` 구문을 사용하여 Markdown, MDX, Markdoc에서 참조할 수 있습니다.

이를 통해 이미지를 `public/` 디렉터리에서 프로젝트 `src/`로 이동하여 처리 및 최적화할 수 있습니다. `public/`에 있는 기존 이미지와 원격 이미지는 여전히 유효하지만 Astro의 빌드 프로세스에 의해 최적화되지 않습니다.

```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/"
# My Markdown Page

<!-- 이제 로컬 이미지가 가능해졌습니다! -->
![A starry night sky.](../../images/stars.png)

<!-- 콘텐츠 옆에 이미지를 보관하세요! -->
![A starry night sky.](./stars.png)
```

이미지 속성에 대한 더 많은 제어가 필요한 경우 Markdown 구문 외에 Astro의 `<Image />` 컴포넌트 또는 JSX `<img />` 태그를 포함할 수 있는 `.mdx` 파일 형식을 사용하는 것이 좋습니다. [MDX 통합](/ko/guides/integrations-guide/mdx/)을 사용하여 Astro에 MDX 지원을 추가하세요.

### `@astrojs/image` 제거

Astro v2.x에서 이미지 통합을 사용하는 경우 다음 단계를 완료하세요.

1. `@astrojs/image` 통합을 제거합니다.

    통합을 제거한 다음 `astro.config.mjs` 파일에서도 [통합을 제거](/ko/guides/integrations-guide/#통합-제거)해야 합니다.

    ```js del={3,7}
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';

    export default defineConfig({
      integrations: [
        image(),
      ]
    })
    ```

2. 타입을 업데이트합니다 (필요한 경우).

		`src/env.d.ts`에 `@astrojs/image`에 대해 구성된 특수 유형이 있는 경우, v3으로 업그레이드해도 이 단계가 완료되지 않으면 이를 기본 Astro 타입으로 다시 변경해야 할 수 있습니다.

		```ts title="src/env.d.ts" del={1} ins={2}
		 /// <reference types="@astrojs/image/client" />
		 /// <reference types="astro/client" />
		```

		마찬가지로 필요한 경우 `tsconfig.json`을 업데이트합니다.

		```json title="tsconfig.json" del={3} ins={4}
		{
			"compilerOptions": {
			  "types": ["@astrojs/image/client"]
			  "types": ["astro/client"]
			}
		}
		```

3. 기존 `<Image />` 컴포넌트를 마이그레이션합니다.

    새로운 내장 `<Image />` 컴포넌트를 사용하려면 모든 `import` 문을 `@astrojs/image/components`에서 `astro:assets`로 변경하세요.

    [현재 지원되는 이미지 자산 속성](#속성)이 아닌 컴포넌트 속성을 제거하세요.

    예를 들어, `aspectRatio`는 이제 `width` 및 `height` 속성에서 자동으로 추론되므로 더 이상 지원되지 않습니다.

      ```astro title="src/components/MyComponent.astro" del= {2,11} ins={3}
      ---
      import { Image } from '@astrojs/image/components';
      import { Image } from 'astro:assets';
      import localImage from '../assets/logo.png';
      const localAlt = 'The Astro Logo';
      ---

      <Image
        src={localImage}
        width={300}
        aspectRatio="16:9"
        alt={localAlt}
      />
      ```

4. 기본 이미지 서비스를 선택합니다.

    [Sharp](https://github.com/lovell/sharp)는 이제 `astro:assets`에 사용되는 기본 이미지 서비스입니다. Sharp를 사용하려면 구성이 필요하지 않습니다.

    [Squoosh](https://github.com/GoogleChromeLabs/squoosh)를 사용하여 이미지를 변환하려면 다음 `image.service` 옵션으로 구성을 업데이트하세요.

    ```js title="astro.config.mjs" ins={4-6}
    import { defineConfig, squooshImageService } from 'astro/config';

    export default defineConfig({
      image: {
        service: squooshImageService(),
      },
    });
    ```

### 콘텐츠 컬렉션 스키마 업데이트

이제 현재 폴더에 대한 상대 경로를 사용하여 블로그 게시물의 표지 이미지와 같은 콘텐츠 컬렉션 항목에 대한 관련 이미지를 프런트매터에서 선언할 수 있습니다.

콘텐츠 컬렉션을 위한 새로운 `image` 도우미를 사용하면 Zod를 사용하여 이미지 메타데이터의 유효성을 검사할 수 있습니다. [콘텐츠 컬렉션에서 이미지를 사용하는 방법](#콘텐츠-컬렉션의-이미지)에 대해 자세히 알아보세요.

### Astro v3.0에서 이미지 가져오기 탐색

Astro v3.0에서는 이미지에 대한 이전 가져오기 동작을 유지해야 하고 이미지 URL의 문자열 표현이 필요한 경우 이미지를 가져올 때 이미지 경로 끝에 `?url`을 추가하세요. 예를 들어:

```astro title="src/pages/blog/MyImages.astro"
---
import Sprite from '../assets/logo.svg?url';
---
<svg>
  <use xlink:href={Sprite + '#cart'} />
</svg>
```

이 접근 방식을 사용하면 URL 문자열을 얻을 수 있습니다. 개발 중에는 Astro가 `src/` 경로를 사용하지만 빌드 시 `/_astro/cat.a6737dd3.png`와 같은 해시된 경로를 생성한다는 점을 명심하세요.

이미지 객체 자체로 직접 작업하려는 경우 `.src` 속성에 액세스할 수 있습니다. 이 접근 방식은 Core Web Vitals 측정항목의 이미지 크기 관리 및 CLS 방지와 같은 작업에 가장 적합합니다.

새로운 가져오기 동작으로 전환하는 경우 `?url`과 `.src` 메서드를 결합하는 것이 원활한 이미지 처리를 위한 올바른 방법일 수 있습니다.
